package org.ddevil.data;

import java.util.List;


/**
 * A mapping of DB Identifiers to view labels.
 * A particular DB Id can only be mapped to one label.
 * The mapping is ordered and calling one of the getAllXXX()methods
 * will return a list in the same order in which the items were added.
 *
 * @author Eric Lundin
 */
public interface DisplayDescriptor extends Cloneable {

    /**
     * Get a list containing all the DB Id's that have mappings
     * in this DisplayDescriptor.  The list will be in the same
     * order in which the mappings were added.
     *
     * @return
     *      An ordered list of all the DB Ids.
     */
	public List<String> getAllIds();

    /**
     * Get a list containing all the labels that are mapped to
     * in this DisplayDescriptor.  The list will be in the same
     * order in which the mappings were added.
     *
     * @return
     *      An ordered list of all the labels.
     */
	public List<String> getAllLabels();

    /**
     * Get the DB Id at the given index.
     *
     * @param index
     *          The index of the DB Id.
     * @return
     *      The DB Id at that index.
     *
     * @throws IndexOutOfBoundsException
     */
	public String getDbIdAtIndex(int index);

    /**
     * Get the index of a given DB Id.
     *
     * @param id
     *          The Id to get the index of.
     * @return
     *      The index of the DB Id.
     *      -1 if there is no mapping for the given DB Id.
     */
	public int getIndexOfId(String id);

    /**
     * Get the label for the given DB Id.
     * This method should return <code>null</code> if
     * this DisplayDescriptor doesn't contain a mapping
     * for the given DB Id.
     *
     * @param id
     *          The DB Id for the label.
     * @return
     *      The label that is mapped to the given DB Id.
     */
	public String getLabel(String id);

    /**
     * Get the DB Id for the given label.
     * <code>null</code> if the label is not in this DisplayDescriptor.
     *
     * @param label
     *      The label whose ID we want.
     * @return
     *      The DB Id for that label.
     */
    public String getIDForLabel(String label);

    /**
     * Remove the mapping for the given DB Id.
     *
     * @param id
     *          The DB Id to remove from this map.
     */
	public void removeLabelById(String id);

    /**
     * Add the DB Id->label mapping to this Display Descriptor.
     * If there is allready a mapping for the given Id then it
     * should be replaced by this new mapping and the new mapping
     * should be in the same spot in the ordered list.  If there
     * is not yet a mapping for the DB Id then one will be added
     * to the end of the list.
     *
     * @param id
     *          The DB Id to label.
     * @param label
     *          The label to map to the given DB Id.
     */
	public void setLabel(String id, String label);

    /**
     * Check if there is a mapping for the given DB Id in this
     * Display Descriptor.
     *
     * @param id
     *          The DB Id to check for.
     * @return
     *      True if there is a mapping for the given DB Id.
     */
    public boolean containsId(String id);

    /**
     * The number of mappings contained in this Display Descriptor.
     *
     * @return
     *      The size.
     */
	public int size();

    /**
     * Return a new DisplayDescriptor object that is a replica
     * of this one.  It will contain all the same mappings and
     * be in the same order.
     * @return
     */
    public DisplayDescriptor clone();
}
